home *** CD-ROM | disk | FTP | other *** search
/ SGI Performance Co-Pilot 1.3 / SGI Performance Co-Pilot 1.3.iso / dist / dist6.4 / pcp.idb / usr / include / pcp / pmapi.h.z / pmapi.h
C/C++ Source or Header  |  1997-04-03  |  16KB  |  507 lines
  1. /* $Id: pmapi.h,v 2.14 1997/03/21 08:28:50 kenmcd Exp $ */
  2.  
  3. #ifndef _PMAPI_H
  4. #define _PMAPI_H
  5.  
  6. #include <stdlib.h>
  7. #include <stdio.h>
  8. #include <unistd.h>
  9. #include <string.h>
  10. #include <malloc.h>
  11. #include <sys/types.h>
  12. #include <sys/param.h>
  13. #include <sys/time.h>
  14.  
  15. #ifdef __cplusplus
  16. extern "C" {
  17. #endif
  18.  
  19. /*
  20.  * -------- Naming Services --------
  21.  */
  22. typedef unsigned int    pmID;        /* Metric Identifier */
  23. #define PM_ID_NULL    0xffffffff
  24.  
  25. typedef unsigned int    pmInDom;    /* Instance-Domain */
  26. #define PM_INDOM_NULL    0xffffffff
  27. #define PM_IN_NULL    0xffffffff
  28.  
  29. #define PM_NS_DEFAULT    (char *)0    /* default name */
  30.  
  31. /*
  32.  * Encoding for the units (dimensions Time and Space) and scale
  33.  * for Performance Metric Values
  34.  *
  35.  * For example, a pmUnits struct of
  36.  *    { 1, -1, 0, PM_SPACE_MBYTE, PM_TIME_SEC, 0 }
  37.  * represents Mbytes/sec, while 
  38.  *    { 0, 1, -1, 0, PM_TIME_HOUR, 6 }
  39.  * represents hours/million-events
  40.  */
  41. typedef struct {
  42.     int    dimSpace:4;    /* space dimension */
  43.     int    dimTime:4;    /* time dimension */
  44.     int    dimCount:4;    /* event dimension */
  45.     int    scaleSpace:4;    /* one of PM_SPACE_* below */
  46.     int    scaleTime:4;    /* one of PM_TIME_* below */
  47.     int    scaleCount:4;    /* one of PM_COUNT_* below */
  48. } pmUnits;            /* dimensional units and scale of value */
  49.  
  50. /* pmUnits.scaleSpace */
  51. #define PM_SPACE_BYTE    0    /* bytes */
  52. #define PM_SPACE_KBYTE    1    /* Kilobytes (1024) */
  53. #define PM_SPACE_MBYTE    2    /* Megabytes (1024^2) */
  54. #define PM_SPACE_GBYTE    3    /* Gigiabytes (1024^3) */
  55. #define PM_SPACE_TBYTE    4    /* Terabytes (1024^4) */
  56. /* pmUnits.scaleTime */
  57. #define PM_TIME_NSEC    0    /* nanoseconds */
  58. #define PM_TIME_USEC    1    /* microseconds */
  59. #define PM_TIME_MSEC    2    /* milliseconds */
  60. #define PM_TIME_SEC    3    /* seconds */
  61. #define PM_TIME_MIN    4    /* minutes */
  62. #define PM_TIME_HOUR    5    /* hours */
  63. /*
  64.  * pmUnits.scaleCount (e.g. count events, syscalls, interrupts, etc.)
  65.  * -- these are simply powers of 10, and not enumerated here,
  66.  *    e.g. 6 for 10^6, or -3 for 10^-3
  67.  */
  68. #define PM_COUNT_ONE    0    /* 1 */
  69.  
  70. /* Performance Metric Descriptor */
  71. typedef struct {
  72.     pmID    pmid;        /* unique identifier */
  73.     int        type;        /* base data type (see below) */
  74.     pmInDom    indom;        /* instance domain */
  75.     int        sem;        /* semantics of value (see below) */
  76.     pmUnits    units;        /* dimension and units */
  77. } pmDesc;
  78.  
  79. /* pmDesc.type -- data type of metric values */
  80. #define PM_TYPE_NOSUPPORT    -1    /* not implemented in this version */
  81. #define PM_TYPE_32        0    /* 32-bit signed integer */
  82. #define PM_TYPE_U32        1    /* 32-bit unsigned integer */
  83. #define PM_TYPE_64        2    /* 64-bit signed integer */
  84. #define PM_TYPE_U64        3    /* 64-bit unsigned integer */
  85. #define PM_TYPE_FLOAT        4    /* 32-bit floating point */
  86. #define PM_TYPE_DOUBLE        5    /* 64-bit floating point */
  87. #define PM_TYPE_STRING        6    /* array of char */
  88. #define PM_TYPE_AGGREGATE    7    /* arbitrary binary data */
  89. #define PM_TYPE_AGGREGATE_STATIC 8      /* static pointer to arbitrary binary data */
  90.  
  91. /* pmDesc.sem -- semantics/interpretation of metric values */
  92. #define PM_SEM_COUNTER    1    /* cumulative counter (monotonic increasing) */
  93.                 /* was PM_SEM_RATE, no longer used now */
  94. #define PM_SEM_INSTANT    3    /* instantaneous value, continuous domain */
  95. #define PM_SEM_DISCRETE    4    /* instantaneous value, discrete domain */
  96.  
  97. /* Generic Union for Value-Type conversions */
  98. typedef union {
  99.     __int32_t    l;    /* 32-bit signed */
  100.     __uint32_t    ul;    /* 32-bit unsigned */
  101.     __int64_t    ll;    /* 64-bit signed */
  102.     __uint64_t    ull;    /* 64-bit unsigned */
  103.     float    f;    /* 32-bit floating point */
  104.     double    d;    /* 64-bit floating point */
  105.     char    *cp;    /* char ptr */
  106.     void    *vp;    /* void ptr */
  107. } pmAtomValue;
  108.  
  109. /* PMAPI Error Conditions */
  110. #define PM_ERR_GENERIC        -1000
  111. #define PM_ERR_PMNS        -1001
  112. #define PM_ERR_NOPMNS        -1002
  113. #define PM_ERR_DUPPMNS        -1003
  114. #define PM_ERR_TEXT        -1004
  115. #define PM_ERR_APPVERSION    -1005
  116. #define PM_ERR_VALUE        -1006
  117. #define PM_ERR_LICENSE        -1007
  118. #define PM_ERR_TIMEOUT        -1008
  119. #define PM_ERR_NODATA        -1009
  120. #define PM_ERR_FILE        -1011
  121. #define PM_ERR_NAME        -1012
  122. #define PM_ERR_PMID        -1013
  123. #define PM_ERR_INDOM        -1014
  124. #define PM_ERR_INST        -1015
  125. #define PM_ERR_UNIT        -1016
  126. #define PM_ERR_CONV        -1017
  127. #define PM_ERR_TRUNC        -1018
  128. #define PM_ERR_SIGN        -1019
  129. #define PM_ERR_PROFILE        -1020
  130. #define PM_ERR_IPC        -1021
  131. #define PM_ERR_NOASCII        -1022
  132. #define PM_ERR_EOF        -1023
  133. #define PM_ERR_NOTHOST        -1024
  134. #define PM_ERR_EOL        -1025
  135. #define PM_ERR_MODE        -1026
  136. #define PM_ERR_LABEL        -1027
  137. #define PM_ERR_LOGREC        -1028
  138. #define PM_ERR_NOTARCHIVE    -1029
  139. #define PM_ERR_NOCONTEXT    -1031
  140. #define PM_ERR_PROFILESPEC    -1032
  141. #define PM_ERR_PMID_LOG        -1033
  142. #define PM_ERR_INDOM_LOG    -1034
  143. #define PM_ERR_INST_LOG        -1035
  144. #define PM_ERR_NOPROFILE    -1036
  145. #define    PM_ERR_NOAGENT        -1041    /* No pmcd agent for domain of request */
  146. #define PM_ERR_PERMISSION    -1042    /* No permission to perform requested operation */
  147. #define PM_ERR_CONNLIMIT    -1043    /* PMCD connection limit for this host exceeded */
  148. #define PM_ERR_AGAIN        -1044    /* try again. Info not currently available */
  149.  
  150. #define PM_ERR_ISCONN        -1045    /* already connected */
  151. #define PM_ERR_NOTCONN        -1046    /* not connected */
  152. #define PM_ERR_NEEDPORT        -1047    /* port name required */
  153. #define PM_ERR_WANTACK        -1048    /* can not send due to pending acks */
  154.  
  155. #define PM_ERR_TOOSMALL        -1098
  156. #define PM_ERR_TOOBIG        -1099
  157.  
  158. #define PM_ERR_NYI        -9999    /* Functionality not yet implemented */
  159.  
  160. /*
  161.  * Report PMAPI errors messages
  162.  */
  163. extern char *pmErrStr(int);
  164.  
  165. /*
  166.  * Load a name space
  167.  */
  168. extern int pmLoadNameSpace(char *);
  169. extern int pmLoadASCIINameSpace(char *, int);
  170.  
  171. /*
  172.  * Trim a name space with respect to the current context
  173.  * (usually from an archive, or after processing an archive)
  174.  */
  175. extern int pmTrimNameSpace(void);
  176.  
  177. /*
  178.  * Expand a list of names to a list of metrics (PM_ID_NULL terminated)
  179.  */
  180. extern int pmLookupName(int, char **, pmID *);
  181.  
  182. /*
  183.  * Find the names of descendent nodes in the PMNS
  184.  */
  185. extern int pmGetChildren(char *, char ***);
  186.  
  187. /*
  188.  * Reverse Lookup: find name(s) given a metric
  189.  */
  190. extern int pmNameID(pmID, char **);        /* one */
  191. extern int pmNameAll(pmID, char ***);        /* all */
  192.  
  193. /*
  194.  * Handy recursive descent of the PMNS
  195.  */
  196. extern int pmTraversePMNS(char *, void(*)(char *));
  197.  
  198. /*
  199.  * Given a metric, find it's descriptor (caller supplies buffer for desc),
  200.  * from the current host context.
  201.  */
  202. extern int pmLookupDesc(pmID, pmDesc *);
  203.  
  204. /*
  205.  * Return the internal instance identifier, from the current host context,
  206.  * given an instance domain and the external instance name.
  207.  * Archive variant scans the union of the indom entries in the archive
  208.  * log.
  209.  */
  210. extern int pmLookupInDom(pmInDom, char *);
  211. extern int pmLookupInDomArchive(pmInDom, char *);
  212.  
  213. /*
  214.  * Return the external instance name, from the current host context,
  215.  * given an instance domain and the internal instance identifier.
  216.  * Archive variant scans the union of the indom entries in the archive
  217.  * log.
  218.  */
  219. extern int pmNameInDom(pmInDom, int, char **);
  220. extern int pmNameInDomArchive(pmInDom, int, char **);
  221.  
  222. /*
  223.  * Return all of the internal instance identifiers (instlist) and external
  224.  * instance names (namelist) for the given instance domain in the current
  225.  * (host) context.
  226.  * Archive variant returns the union of the indom entries in the archive
  227.  * log.
  228.  */
  229. extern int pmGetInDom(pmInDom, int **, char ***);
  230. extern int pmGetInDomArchive(pmInDom, int **, char ***);
  231.  
  232. /*
  233.  * return the handle of the current context
  234.  */
  235. extern int pmWhichContext(void);
  236.  
  237. /*
  238.  * destroy a context and close it's connection
  239.  */
  240. extern int pmDestroyContext(int);
  241.  
  242. /*
  243.  * Establish a new context (host + instance profile) for the named host
  244.  */
  245. extern int pmNewContext(int, char *);
  246. #define PM_CONTEXT_HOST        1    /* context types */
  247. #define PM_CONTEXT_ARCHIVE    2
  248.  
  249. /*
  250.  * Duplicate current context -- returns handle to new one for pmUseContext()
  251.  */
  252. extern int pmDupContext(void);
  253.  
  254. /*
  255.  * Restore (previously established or duplicated) context
  256.  */
  257. extern int pmUseContext(int);
  258.  
  259. /*
  260.  * Reconnect an existing context (when pmcd dies, etc)
  261.  * All existing context settings are preserved.
  262.  */
  263. extern int pmReconnectContext(int);
  264.  
  265. /*
  266.  * Add to instance profile.
  267.  * If pmInDom == PM_INDOM_NULL, then all instance domains are selected.
  268.  * If no inst parameters are given, then all instances are selected.
  269.  * E.g. select all available instances in all domains,
  270.  * then use pmProfileAdd(PM_INDOM_NULL);
  271.  */
  272. extern int pmAddProfile(pmInDom, int, int *);
  273.  
  274. /*
  275.  * Delete from instance profile.
  276.  * Similar (but negated) functional semantics to pmProfileAdd.
  277.  * E.g. to disable all instances in all domains: pmProfileDel(PM_INDOM_NULL);
  278.  */
  279. extern int pmDelProfile(pmInDom, int, int *);
  280.  
  281. /* 
  282.  * ---------- Collection services ---------- 
  283.  *
  284.  * Result from pmFetch is encoded as a timestamp and vector of pointers
  285.  * to pmValueSet instances (one per PMID in the result).
  286.  * Each pmValueSet has a PMID, a value count, a value format, and a vector of
  287.  * instance-value pairs.  Aggregate, string and non-int values are returned
  288.  * via one further level of indirection using pmValueBlocks.
  289.  *
  290.  * timeStamp
  291.  * ->pmID
  292.  *   value format
  293.  *     instance, value
  294.  *     instance, value
  295.  *     ... etc
  296.  *
  297.  * ->pmID
  298.  *   value format
  299.  *     instance, value
  300.  *     ... etc
  301.  *
  302.  *
  303.  * Notes on pmValueBlock
  304.  *   0. may be used for arbitrary binary data
  305.  *   1. only ever allocated dynamically, and vbuf expands to accommodate
  306.  *    an arbitrary value (don't believe the [1] size!)
  307.  *   2. len is the length of the len field + the real size of vbuf
  308.  *    (which includes the null-byte terminator if there is one)
  309.  */
  310. typedef struct {
  311.     int        len;        /* length in bytes */
  312.     char    vbuf[1];    /* the value */
  313. } pmValueBlock;
  314.  
  315. typedef struct {
  316.     int        inst;        /* instance identifier */
  317.     union {
  318.     pmValueBlock    *pval;    /* pointer to value-block */
  319.     int        lval;    /* integer value insitu (ival 'cuz it WAS a long) */
  320.     } value;
  321. } pmValue;
  322.  
  323. typedef struct {
  324.     pmID    pmid;        /* metric identifier */
  325.     int        numval;        /* number of values */
  326.     int        valfmt;        /* value style */
  327.     pmValue    vlist[1];    /* set of instances/values */
  328. } pmValueSet;
  329.  
  330. /* values for valfmt */
  331. #define PM_VAL_INSITU    0    /* value.ival is it */
  332. #define PM_VAL_DPTR    1    /* value.pval->vbuf is it, and dynamic alloc */
  333. #define PM_VAL_SPTR    2    /* value.pval->vbuf is it, and static alloc */
  334.  
  335. /* Result returned by pmFetch() */
  336. typedef struct {
  337.     struct timeval    timestamp;    /* time stamped by collector */
  338.     int        numpmid;        /* number of PMIDs */
  339.     pmValueSet    *vset[1];        /* set of value sets, one per PMID */
  340. } pmResult;
  341.  
  342.  
  343. /*
  344.  * Fetch metrics. Value/instances returned depends on current instance profile.
  345.  * By default, all available instances for each requested metric id are
  346.  * returned. The metrics argument is terminated with PM_NULL_ID
  347.  *
  348.  * The value sets returned are in the same order as the metrics argument,
  349.  * and the number of value sets returned is guaranteed to be the same as
  350.  * the number of metrics in the agument.  
  351.  */
  352. extern int pmFetch(int, pmID *, pmResult **);
  353.  
  354. /*
  355.  * variant that is used to return a pmResult from an archive
  356.  */
  357. extern int pmFetchArchive(pmResult **);
  358.  
  359. /*
  360.  * Label Record at the start of every log file - as exported above
  361.  * the PMAPI ... note that the struct timeval means we have another
  362.  * struct (_pmLogLabel32) for internal use that has a timeval_32 in
  363.  * place of the struct timeval.
  364.  */
  365. #define PM_LOG_MAGIC    0x50052600
  366. #define PM_LOG_VERS01    0x1
  367. #define PM_LOG_VOL_TI    -2    /* temporal index */
  368. #define PM_LOG_VOL_META    -1    /* meta data */
  369. typedef struct {
  370.     int        ll_magic;    /* PM_LOG_MAGIC | log format version no. */
  371.     pid_t    ll_pid;        /* PID of logger */
  372.     struct timeval    ll_start;        /* start of this log */
  373.     char    ll_hostname[MAXHOSTNAMELEN];    /* name of collection host */
  374.     char    ll_tz[40];    /* $TZ at collection host */
  375. } pmLogLabel;
  376.  
  377. /*
  378.  * get the label record from the current archive context, and discover
  379.  * when the archive ends
  380.  */
  381. extern int pmGetArchiveLabel(pmLogLabel *);
  382. extern int pmGetArchiveEnd(struct timeval *);
  383.  
  384. /* Free result buffer */
  385. extern void pmFreeResult(pmResult *);
  386.  
  387. /* Value extract from pmValue and type conversion */
  388. extern int pmExtractValue(int, pmValue *, int, pmAtomValue *, int);
  389.  
  390. /* Print single pmValue */
  391. extern void pmPrintValue(FILE *, int, int, pmValue *, int);
  392.  
  393. /* Scale conversion, based on value format, value type and scale */
  394. extern int pmConvScale(int, pmAtomValue *, pmUnits *, pmAtomValue *, pmUnits *);
  395.  
  396. /* Sort instances for each metric within a pmResult */
  397. extern void pmSortInstances(pmResult *);
  398.  
  399. /* Adjust collection time and/or mode for pmFetch */
  400. extern int pmSetMode(int, struct timeval *, int);
  401. #define PM_MODE_LIVE    0
  402. #define PM_MODE_INTERP    1
  403. #define PM_MODE_FORW    2
  404. #define PM_MODE_BACK    3
  405.  
  406. /* Modify the value of one or more metrics */
  407. extern int pmStore(pmResult *);
  408.  
  409. /* Get help and descriptive text */
  410. extern int pmLookupText(pmID, int, char **);
  411. extern int pmLookupInDomText(pmInDom, int, char **);
  412. #define PM_TEXT_ONELINE    1
  413. #define PM_TEXT_HELP    2
  414.  
  415. /*
  416.  * some handy formatting routines for messages, and other output
  417.  */
  418. extern char *pmIDStr(pmID);
  419. extern char *pmInDomStr(pmInDom);
  420. extern char *pmTypeStr(int);
  421. extern char *pmUnitsStr(pmUnits *);
  422. extern char *pmAtomStr(pmAtomValue *, int);
  423.  
  424.  
  425.  
  426. /* time control client commands, returned by pmTimeRecv() */
  427. #define PM_TCTL_SET        0    /* goto new position, set delta */
  428. #define PM_TCTL_STEP        1    /* update (i.e. fetch), ACK required */
  429. #define PM_TCTL_SKIP        2    /* step (but don't fetch, live only) */
  430. #define PM_TCTL_VCRMODE        3    /* change vcr modes */
  431. #define PM_TCTL_TZ        4    /* use a new timezone (tzlabel and tz)*/
  432. #define PM_TCTL_SHOWDIALOG    5    /* show/hide time controls dialog */
  433. #define PM_TCTL_BOUNDS        6    /* use new archive bounds */
  434.  
  435. /* time control vcr mode indicators */
  436. #define PM_TCTL_VCRMODE_STOP    0    /* expect long pause */
  437. #define PM_TCTL_VCRMODE_PLAY    1    /* expect slow seq of PM_TCTL_STEP */
  438. #define PM_TCTL_VCRMODE_FAST    2    /* expect rapid seq of PM_TCTL_STEP */
  439. #define PM_TCTL_VCRMODE_DRAG    3    /* expect rapid seq of PM_TCTL_SET */
  440.  
  441. /* time control connection modes (bitmap) */
  442. #define PM_TCTL_MODE_STANDALONE    1    /* stand-alone mode, single client */
  443. #define PM_TCTL_MODE_MASTER    2    /* use an existing master controller */
  444. #define PM_TCTL_MODE_NEWMASTER    4    /* create new master controller */
  445.  
  446. #define PM_TCTL_MODE_HOST    8    /* live mode (stop/step available only) */
  447. #define PM_TCTL_MODE_ARCHIVE    16    /* archive mode (full VCR controls) */
  448.  
  449. /* time control state data */
  450. typedef struct {
  451.     int            showdialog;    /* non-zero => time control dialog is visible */
  452.     struct timeval    position;    /* current time / archive position */
  453.     int            delta;        /* update interval +-milliseconds */
  454.     char        tzlabel[40];    /* name of current time zone */
  455.     char        tz[40];        /* current time zone */
  456.     struct timeval    start;        /* controller's current starting time */
  457.     struct timeval    finish;        /* controller's current finish time */
  458.     int            vcrmode;    /* PM_TCTL_VCRMODE_STOP .. PM_TCTL_VCRMODE_DRAG */
  459. } pmTime;
  460.  
  461. /*
  462.  * Connect to time controller in given mode, returns read fd (or err < 0).
  463.  * If standalone or new master then use given initial state.
  464.  */
  465. extern int pmTimeConnect(int, char *, pmTime *); /* mode, port, initState */
  466.  
  467. /* disconnect from time control master or standalone, free internal state. */
  468. extern int pmTimeDisconnect(void);
  469.  
  470. /* return port name (in static buffer), or NULL if standalone */
  471. extern char *pmTimeGetPort(void);
  472.  
  473. /* receive a time control command (may block), returns command (or err < 0) */
  474. extern int pmTimeRecv(pmTime *); /* commandBuffer */
  475.  
  476. /* send ack that PM_TCTL_STEP has been processed */
  477. extern int pmTimeSendAck(struct timeval *); /* actualFetchTime */
  478.  
  479. /* send earliest and latest archive bounds */
  480. extern int pmTimeSendBounds(struct timeval *, struct timeval *);
  481.  
  482. /* send a label and a timezone string */
  483. extern int pmTimeSendTimezone(char *, char *);
  484.  
  485. /* show/hide the master time control dialog */
  486. extern int pmTimeShowDialog(int); /* 0==hide else show */
  487.  
  488. /* return a char pixmap representing vcrmode (0..3) dir (-1, 0, 1), live (0, 1), record (0, 1) */
  489. extern const char **pmTimeGetStatePixmap(int, int, int, int); /* vcrmode, dir, live, record */
  490.  
  491. /* parse -S, -T, -A and -O options */
  492. extern int pmParseTimeWindow(
  493.       char *, char *, char *, char *,
  494.       struct timeval *, struct timeval *,
  495.       struct timeval *, struct timeval *, struct timeval *, char **);
  496.  
  497.  
  498. #ifdef MALLOC_AUDIT
  499. #include "malloc-audit.h"
  500. #endif
  501.  
  502. #ifdef __cplusplus
  503. }
  504. #endif
  505.  
  506. #endif /* _PMAPI_H */
  507.